Workshop 2 - RMarkdown
We want to present the results and the visuals in ways that are easier to share with people. We will knit the RMarkdown file into a PDF or a webpage, so people can have all the info in one place (together with the code if it is a webpage).
RMarkdown is a file format to make dynamic documents in R. You can include analyses with outputs, graphs, text to explain your analysis, photos and hyperlinks. This page you are looking at right now is produced from an RMarkdown file! The RMarkdown file consists of text and chunks of code. This allows you to provide formatted explanations alongside your code and analysis.
Check out these useful links (below) to learn more.
As we have mentioned in the last workshop (or not), we suggest you to have some specific folders to keep everything tidy.
We will use RMarkdown to create a webpage and publish the page as a GitHub page online.
example 1 - Visual models
example 2 - Heating rate
Let’s take a closer look what we can have in a website
There are two files you need to have to publish a webpage:
Exercise 1: Copy the Website repo from Bug of the week to your own GitHub.
You can create RMarkdown files and set the output into html format.
Where to set it?
You will set the output formate and
appearance in the yaml header of your RMarkdown file.
What and where
is the yaml header?
In (very) short, it controls the overall
appearance of the page and it is on the top of the file like
this:
---
title: "Workshop 2: RMarkdown"
author: "Amanda Franklin, Laura Ospina, Lu-Yi Wang"
date: "4/25/2022"
output: html_document
knit: (function(inputFile, encoding) {
rmarkdown::render(inputFile, encoding = encoding, output_dir = "../docs") })
---See here and here for more details about yaml.
Note: You would like to save your output html files in the docs folder. To do so, you will need to change the directory in the yaml header using the following code:
knit: (function(inputFile, encoding) {
rmarkdown::render(inputFile, encoding = encoding, output_dir = "../docs") })Exercise 2: Create 2 RMarkdown pages. Knit them into html and save them in the docs folder. Try to apply the syntax Amanda just showed you.
For making buttons, you can use the following code after #, then the headers of the immediate lower level will turn into tabs.
{.tabset .tabset-fade .tabset-pills}
#e.g.
## Header 2 {.tabset .tabset-fade .tabset-pills}
### Header 3.1
bla bla bla
### Header 3.2
bla bla bla
# Here, you will get two tabs which are "Header 3.1" and "Header 3.2"Remember that we need a index.html file for the homepage? You can
either assgin one of the pages you create as the homepage by changing
the name of the corresponding .Rmd file to index and knit it again, or
you can create a new .Rmd file and call it index.
To link to the other page, you an use the following code
[text](html file name/http address)
# For example, if in the same folder
# [Workshop 1: Github](workshopGithub.html)
# Or [Bug of the week](https://github.com/bugoftheweek)Exercise 3: Make your index.html file and try to link it to the pages you just made.
We have created two separate pages. How do we combine them into one
site?
To do this, we need the _site.yml file (need to be
specifically called _site.yml).
Note: You need to place the _site.yml file in the same folder as other .Rmd files
Change the file type to .yml by adding “.yml” at the end of the file. After this, open the .yml file from RStudio instead of directly from the folder.
Inside the _site.yml file Whatever you put here will overwrite the ymal header in the separate .Rmd files. In side the file, we will specify things including the headers, the table, the theme, and the output directory.
Note: you need to set the output directory to the same folder (docs) as other html to be able to combine them into one site
name: "Lab Workshop"
navbar:
title: ""
subtitle: Supplementary Information
Date: "April 25th 2022"
left: # left side of the header
- text: "Introduction"
href: index.html
- text: "Workshop 1: Github"
href: workshopGithub.html
- text: "Workshop 2: RMarkdown"
href: workshopRMarkdown.html
right: # right side of the header
- icon: fa-github # icon of GitHub
text: Bug of the week
href: https://github.com/bugoftheweek # You can also have a http address
output:
html_document:
toc: true # table of content true
toc_float: # have a table of content at the left side
collapsed: true # default true, only show up tp level 2 unless click to expand
smooth_scroll: true # animated the page to the clicked item
depth: 6 # up to three depths of headings (specified by #, ## and ###)
number_sections: false # number sections at each table header
theme: flatly # theme for fonts and colours
highlight: tango # different theme for the appearance of the code
output_dir: "../docs"Exercise 4: Make some edits (e.g. headers) in your _site.yml file!
Now we are going to make the site go online!
Be sure your repo is public. If not, got to Setting -> Genral -> scroll to the end.
In the Setting, on the left table, click Pages
Change the branch to “main” and the folder to “docs” cause that is where the index.html is.
You made it! But it will take a couple minutes till the link starts to work.
Exercise 4: Try to publish your page!
To knit into a PDF, you don’t need the .yml file but you need to do is to change the output format into “pdf_document”.
output: pdf_documentNote: There are some difference in syntax between the html and PDF formats and some functions are available for html output but not for PDF one, e.g. tabs, code buttons. So they are not completely compatible.
If you choose the output format to PDF upon creating the RMarkdown, it will automatically assign the output format to PDF. But you need to change the output directory to the docs folder manually on the yaml header.
To knit an RMkarkdown into PDF,you will need to install LaTeX on you computer. The simplest way is to install TinyTeX and you can run the following code from here in R to install it.
install.packages('tinytex')
tinytex::install_tinytex()If you want to include a content table on the first page of the PDF, you can add the following code in the yaml header:
output:
pdf_document:
toc: true # To have the content table or not
toc_depth: 3 # To which level of the headers you want to includeExercise 5: Try to make one RMarkdown file and knit it into a PDF.
Note: If you put the .Rmd file that you want to knit into PDF in the
same folder as your _site.yml, the .Rmd will be knitted into an html
file because the yaml header in the _site.yml overrides the the ymal
header in .Rmd files if they are in the same directory.
Hence, you
need to create another script folder for the Rmd files that you want to
knit into PDFs.
Have useful code for some amazing features/figures.